<?php

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */

/**
 * This file contains the Session_Store class.
 *
 * PHP version 5
 *
 * This file is part of Majic - A rapid-development web application framework
 * for PHP 5.
 *
 * Majic is free software: you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License as published by the Free
 * Software Foundation, either version 3 of the License, or (at your option)
 * any later version.
 *
 * Majic is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
 * details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with Majic. If not, see <http://www.gnu.org/licenses/>.
 *
 * @package     Session
 * @author      Michael J. I. Jackson <mjijackson@gmail.com>
 * @copyright   2007-2008 Michael J. I. Jackson
 * @license     http://www.gnu.org/licenses/lgpl-3.0.txt GNU LGPL 3.0
 * @version     SVN: $Id: Store.php 34 2008-07-19 04:50:53Z mjijackson $
 */

/**
 * The base class for all session stores. A session store is responsible for
 * storing session data.
 *
 * @package     Session
 * @author      Michael J. I. Jackson <mjijackson@gmail.com>
 */
abstract class Session_Store
{

    /**
     * Constructor.
     *
     * @access  public
     */
    public function __construct() {}

    /**
     * Sets the session module name and save handler.
     *
     * @return  void
     * @access  public
     */
    public function set()
    {
        session_module_name('user');
        session_set_save_handler(
            array($this, 'open'),
            array($this, 'close'),
            array($this, 'read'),
            array($this, 'write'),
            array($this, 'destroy'),
            array($this, 'gc')
        );
    }

    /**
     * Called when a session is initialized.
     *
     * @param   string  $save_path      The path where session files are stored
     * @param   string  $name           The session name
     * @return  bool                    True on success, false on failure
     * @access  public
     * @abstract
     */
    abstract public function open($save_path, $name);

    /**
     * Called when a session is shut down.
     *
     * @return  bool                    True on success, false on failure
     * @access  public
     * @abstract
     */
    abstract public function close();

    /**
     * Called when the session is started. Should return a serialized string
     * of session data from the session with the given id. If no session with
     * the given id can be found, should return an empty string. Should return
     * false on error.
     *
     * @param   string  $id             A hash of the session id
     * @return  string                  The serialized session data
     * @access  public
     * @abstract
     */
    abstract public function read($id);

    /**
     * Updates an existing session's data if one with the given id exists, or
     * creates a new store with the given id and data.
     *
     * @param   string  $id             A hash of the session id
     * @param   string  $data           The serialized session data
     * @return  bool                    True on success, false on failure
     * @access  public
     * @abstract
     */
    abstract public function write($id, $data);

    /**
     * Removes all data from the store for the session with the given id.
     *
     * @param   string  $id             A hash of the session id
     * @return  bool                    True on success, false on failure
     * @access  public
     * @abstract
     */
    abstract public function destroy($id);

    /**
     * Deletes old, stale sessions that are still contained in the data store.
     *
     * @param   int     $maxlifetime    The maximum session lifetime
     * @return  bool                    True on success, false on failure
     * @access  public
     * @abstract
     */
    abstract public function gc($maxlifetime);

    /**
     * Explicitly calls {@link http://php.net/session_write_close session_write_close()}
     * to ensure that stores correctly write out session data.
     *
     * @return  void
     * @access  public
     */
    public function __destruct()
    {
        session_write_close();
    }

}

?>
